Quarto Essentials

Bogdan G. Popescu
bogdan.popescu@johncabot.edu

John Cabot University

Introduction

What is Quarto

Quarto - open-source publishing system designed for creating dynamic, reproducible documents, including reports, presentations, and websites.

It supports multiple formats like HTML, PDF, Word, and slides.

Why Use Quarto?

  • Integrates well with R, Python, and Julia.
  • Enables embedding of code chunks directly in documents for dynamic content generation.
  • Facilitates reproducibility by linking code and results seamlessly.

Quarto Document Structure

YAML Header

  • The YAML header defines the document metadata, such as title, author, date, and output format.
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
---

# Introduction

This is an example.

Input

Quarto Document Structure

YAML Header

  • The YAML header defines the document metadata, such as title, author, date, and output format.
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
---

# Introduction

This is an example.

Output

Creating HTML Output

Basic YAML Configuration:

To generate an HTML file, specify format: html in the YAML header.

Rendering the Document:

  • Use quarto render in R to generate the output.

Adding a Table of Contents

Enabling TOC:

  • Add toc: true in the YAML header to automatically generate a table of contents.

  • Control depth with toc-depth (e.g., 2 for two levels of headings).

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
---

# Introduction

This is an example.

Output

Adding a Table of Contents

Customization:

  • Rename the title with toc-title: "Contents".
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

Output

Equations

Equations

Use $ delimiters for inline math and $$ delimiters for display math. For example:

Markdown Syntax Output 
inline math: $E = mc^{2}$
 inline math: \(E=mc^{2}\) 
display math:

$$E = mc^{2}$$

display math:

\[E = mc^{2}\]

Code and Tabsets

Embedding Code

This is how we include code in our documents.

```{r}
summary(mtcars)
```
      mpg             cyl             disp             hp       
 Min.   :10.40   Min.   :4.000   Min.   : 71.1   Min.   : 52.0  
 1st Qu.:15.43   1st Qu.:4.000   1st Qu.:120.8   1st Qu.: 96.5  
 Median :19.20   Median :6.000   Median :196.3   Median :123.0  
 Mean   :20.09   Mean   :6.188   Mean   :230.7   Mean   :146.7  
 3rd Qu.:22.80   3rd Qu.:8.000   3rd Qu.:326.0   3rd Qu.:180.0  
 Max.   :33.90   Max.   :8.000   Max.   :472.0   Max.   :335.0  
      drat             wt             qsec             vs        
 Min.   :2.760   Min.   :1.513   Min.   :14.50   Min.   :0.0000  
 1st Qu.:3.080   1st Qu.:2.581   1st Qu.:16.89   1st Qu.:0.0000  
 Median :3.695   Median :3.325   Median :17.71   Median :0.0000  
 Mean   :3.597   Mean   :3.217   Mean   :17.85   Mean   :0.4375  
 3rd Qu.:3.920   3rd Qu.:3.610   3rd Qu.:18.90   3rd Qu.:1.0000  
 Max.   :4.930   Max.   :5.424   Max.   :22.90   Max.   :1.0000  
       am              gear            carb      
 Min.   :0.0000   Min.   :3.000   Min.   :1.000  
 1st Qu.:0.0000   1st Qu.:3.000   1st Qu.:2.000  
 Median :0.0000   Median :4.000   Median :2.000  
 Mean   :0.4062   Mean   :3.688   Mean   :2.812  
 3rd Qu.:1.0000   3rd Qu.:4.000   3rd Qu.:4.000  
 Max.   :1.0000   Max.   :5.000   Max.   :8.000

Code and Tabsets

Embedding Code

The following options print the code but do not evaluate the code

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

Code and Tabsets

Embedding Code

The following options print the code and evaluates the code

```{r echo=TRUE, eval=TRUE}
summary(mtcars)
```
      mpg             cyl             disp             hp       
 Min.   :10.40   Min.   :4.000   Min.   : 71.1   Min.   : 52.0  
 1st Qu.:15.43   1st Qu.:4.000   1st Qu.:120.8   1st Qu.: 96.5  
 Median :19.20   Median :6.000   Median :196.3   Median :123.0  
 Mean   :20.09   Mean   :6.188   Mean   :230.7   Mean   :146.7  
 3rd Qu.:22.80   3rd Qu.:8.000   3rd Qu.:326.0   3rd Qu.:180.0  
 Max.   :33.90   Max.   :8.000   Max.   :472.0   Max.   :335.0  
      drat             wt             qsec             vs        
 Min.   :2.760   Min.   :1.513   Min.   :14.50   Min.   :0.0000  
 1st Qu.:3.080   1st Qu.:2.581   1st Qu.:16.89   1st Qu.:0.0000  
 Median :3.695   Median :3.325   Median :17.71   Median :0.0000  
 Mean   :3.597   Mean   :3.217   Mean   :17.85   Mean   :0.4375  
 3rd Qu.:3.920   3rd Qu.:3.610   3rd Qu.:18.90   3rd Qu.:1.0000  
 Max.   :4.930   Max.   :5.424   Max.   :22.90   Max.   :1.0000  
       am              gear            carb      
 Min.   :0.0000   Min.   :3.000   Min.   :1.000  
 1st Qu.:0.0000   1st Qu.:3.000   1st Qu.:2.000  
 Median :0.0000   Median :4.000   Median :2.000  
 Mean   :0.4062   Mean   :3.688   Mean   :2.812  
 3rd Qu.:1.0000   3rd Qu.:4.000   3rd Qu.:4.000  
 Max.   :1.0000   Max.   :5.000   Max.   :8.000

Code and Tabsets

Embedding Code

The following options do not print but evaluates the code

```{r echo=FALSE, eval=TRUE}
summary(mtcars)
```
      mpg             cyl             disp             hp       
 Min.   :10.40   Min.   :4.000   Min.   : 71.1   Min.   : 52.0  
 1st Qu.:15.43   1st Qu.:4.000   1st Qu.:120.8   1st Qu.: 96.5  
 Median :19.20   Median :6.000   Median :196.3   Median :123.0  
 Mean   :20.09   Mean   :6.188   Mean   :230.7   Mean   :146.7  
 3rd Qu.:22.80   3rd Qu.:8.000   3rd Qu.:326.0   3rd Qu.:180.0  
 Max.   :33.90   Max.   :8.000   Max.   :472.0   Max.   :335.0  
      drat             wt             qsec             vs        
 Min.   :2.760   Min.   :1.513   Min.   :14.50   Min.   :0.0000  
 1st Qu.:3.080   1st Qu.:2.581   1st Qu.:16.89   1st Qu.:0.0000  
 Median :3.695   Median :3.325   Median :17.71   Median :0.0000  
 Mean   :3.597   Mean   :3.217   Mean   :17.85   Mean   :0.4375  
 3rd Qu.:3.920   3rd Qu.:3.610   3rd Qu.:18.90   3rd Qu.:1.0000  
 Max.   :4.930   Max.   :5.424   Max.   :22.90   Max.   :1.0000  
       am              gear            carb      
 Min.   :0.0000   Min.   :3.000   Min.   :1.000  
 1st Qu.:0.0000   1st Qu.:3.000   1st Qu.:2.000  
 Median :0.0000   Median :4.000   Median :2.000  
 Mean   :0.4062   Mean   :3.688   Mean   :2.812  
 3rd Qu.:1.0000   3rd Qu.:4.000   3rd Qu.:4.000  
 Max.   :1.0000   Max.   :5.000   Max.   :8.000

Code and Tabsets

Embedding Code

Many times you might have seen annoying library messages:

```{r}
library(dplyr)
```
Attaching package: 'dplyr'
The following object is masked from 'package:gridExtra':

    combine
The following objects are masked from 'package:stats':

    filter, lag
The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union

Code and Tabsets

Embedding Code

To avoid them in printing, you should do:

```{r warning=FALSE, message=FALSE}
library(dplyr)
```

Embedding Resources

What is Self-Contained HTML?:

An HTML document that includes all dependencies (images, CSS, JavaScript) within a single file.

Why Use It?

Easy to share and view without requiring external resources.

This means that you will only see an html document being produced.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
embed-resources: true
---

# Introduction

This is an example.

Text Formatting

Markdown Syntax Output 
*italics*, **bold**, ***bold italics***
 italics, bold, bold italics 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Headings

Markdown Syntax Output 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

 
##### Header 5
Header 5
 
###### Header 6
Header 6

Lists

Markdown Syntax Output 
* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1
  • unordered list
    • sub-item 1
    • sub-item 2
      • sub-sub-item 1
 
*   item 2

    Continued (indent 4 spaces)

  • item 2

    Continued (indent 4 spaces)

Lists

Markdown Syntax Output 
1. ordered list
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1
  1. ordered list
  2. item 2
    1. sub-item 1
      1. sub-sub-item 1
 
- [ ] Task 1
- [x] Task 2

Lists

Markdown Syntax Output 
::: {}
1. A list
:::

::: {}
1. Followed by another list
:::
  1. A list
  1. Followed by another list
 
term
: definition
term
definition

Tables

Markdown Syntax

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Output

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Diagrams

Quarto has native support for embedding Mermaid and Graphviz diagrams.

This enables you to create flowcharts, sequence diagrams, state diagrams.

For example, here we embed a flowchart created using Mermaid:

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Videos

You can include videos in documents using the {{< video >}} shortcode. For example, here we embed a YouTube video:

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

Videos can refer to video files (e.g. MPEG) or can be links to videos published on YouTube, Vimeo, or Brightcove.

Callout Blocks

Markdown Syntax

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Output

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Word Basics

Use the docx format to create MS Word output. For example:

---
title: "My Document"
format:
  docx:
    toc: true
    number-sections: true
    highlight-style: github
---

Table of Contents

Use the toc option to include an automatically generated table of contents in the output document.

Use the toc-depth option to specify the number of section levels to include in the table of contents.

The default is 3 (which means that level-1, 2, and 3 headings will be listed in the contents). For example:

---
title: "My Document"
format:
  docx:
    toc: true
    toc-depth: 2
    number-sections: true
    highlight-style: github
---

Table of Contents and Section Numbering

If you want to exclude a heading from the table of contents, add both the .unnumbered and .unlisted classes to it:

### More Options {.unnumbered .unlisted}

Use the number-sections option to number section headings in the output document. For example:

number-sections: true

PDF Basics

Use the pdf format to create PDF output. For example:

---
title: "My document"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

Prerequisites

In order to create PDFs you will need to install a recent distribution of TeX. We recommend the use of TinyTeX (which is based on TexLive), which you can install with the following command:

Terminal
quarto install tinytex

Document Class

Quarto uses KOMA Script document classes by default for PDF documents and books.

For PDF documents this results in the following Pandoc options set by default:

format:
  pdf:
    documentclass: scrartcl
    papersize: letter

You can set documentclass to the standard article, report or book classes.

Note

Setting your documentclass to either book or scrbook will automatically handle many of the common needs for printing and binding PDFs into a physical book.

Output Options

There are numerous options available for customizing PDF output, including:

  • Specifying document classes and their options

  • Including lists of figures and tables

  • Numerous options for customizing fonts and colors.

For example, here we use a few of these options:

Output Options

Here is an example:

---
title: "My Document"
format: 
  pdf: 
    documentclass: report
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    mainfont: Times New Roman
    colorlinks: true
---

Quarto Manuscripts

Quarto manuscript projects provide a framework for writing and publishing scholarly articles.

By using one or more notebooks or .qmd documents as the source of content and computations, computations can be published alongside the manuscript, allowing readers to dive into your code.

It is possible to produce manuscripts in multiple formats (including LaTeX or MS Word)

Quarto Manuscripts

The output of a Quarto manuscript is a website (live example)

Conclusion

There are lots of options for Quarto Documents:

Checkout the Quarto Guide

Most relevant are:

  • Authoring
  • Computations
  • Documents
  • Presentations

Implications for Assignments

Please make sure that your assignments looks nice from now on :)

You can find the answers to assignment 2 qmd as a model.

Popescu (JCU): Quarto Essentials